Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:SavePanel;,SavePanel

Inherits From:	Panel : Window : Responder : Object

Declared In:	appkit/SavePanel.h

Class Description

The SavePanel provides a simple way for an application to query the user for the name of a file to use when saving a document or other data.  It allows the application to restrict the file name to have a certain file type, as specified by a file name extension.  There is one and only one SavePanel in an application and the new method returns a pointer to it.

Whenever the user actually decides on a file name, the message panelValidateFilenames: is sent to the SavePanel's delegate (if it responds to that message).  The delegate can then determine whether that file name can be used; it returns YES if the file name is valid, or NO if the SavePanel should stay up and wait for the user to type in a different file name.  The delegate can also implement a panel:filterFile:inDirectory: method to test that both the file name and the directory are valid.

Instance Variables

id form;

id browser;

id okButton;

id accessoryView;

id separator;

char *filename;

char *directory;

const char **filenames;

char *requiredType;

struct _spFlags {
	unsigned int  opening:1;
	unsigned int  exitOk:1;
	unsigned int  allowMultiple:1;
	unsigned int  dirty:1;
	unsigned int  invalidateMatrices:1;
	unsigned int  filtered:1;

}	spFlags;

unsigned short  directorySize;

form 	The form in which the user types file names

browser 	The browser displaying the file hierarchy

okButton 	The OK button

accessoryView 	Application-customized area

separator 	The line separating the icon from the rest of the panel

filename 	The chosen file name

directory 	The directory of the chosen file

filenames 	The list of chosen files

requiredType 	The type of file to save

spFlags.opening 	Specifies whether file is being opened or saved

spFlags.exitOk 	Exit status

spFlags.allowMultiple 	Whether to allow multiple files

spFlags.dirty 	Dirty flag for invisible updates

spFlags.invalidateMatrices 	Whether the matrices are valid

spFlags.filtered 	Whether types are filtered

directorySize 	Length of the directory string

Method Types

Creating and freeing a SavePanel
+ newContent:style:backing:buttonMask:defer:
- free

Setting the SavePanel class	+ setSavePanelFactory:

Customizing the SavePanel	- setAccessoryView: 
- accessoryView
- setTitle:
- setPrompt:

Setting directory and file type	- setDirectory: 
- setRequiredFileType:
- requiredFileType

Handling file packages	- doesTreatFilePackagesAsDirectories
- setTreatsFilePackagesAsDirectories:

Running the SavePanel	- runModal
- runModalForDirectory:file:

Reading save information	- directory
- filename

Completing a partial filename	- commandKey:

Action methods	- cancel: 
- ok:

Responding to user input	- selectText: 
- textDidGetKeys:isEmpty: 
- textDidEnd:endChar:

Setting the delegate	- setDelegate: 
- delegate (Window)

Class Methods

NS_DEV_DOCFOR:objc_method:[SavePanel-alloc];,alloc

+ alloc

Generates an error message.  This method cannot be used to create SavePanel instances.  Use the newContent:style:backing:buttonMask:defer: method instead.

See also:   + newContent:style:backing:buttonMask:defer:

NS_DEV_DOCFOR:objc_method:[SavePanel-allocFromZone:];,allocFromZone:

+ allocFromZone:(NXZone *)zone

Generates an error message.  This method cannot be used to create SavePanel instances.  Use the newContent:style:backing:buttonMask:defer: method instead.

See also:  + newContent:style:backing:buttonMask:defer:

NS_DEV_DOCFOR:objc_method:[SavePanel-newContent:style:backing:buttonMask:defer:];,newContent:style:backing:buttonMask:defer:

+ newContent:(const NXRect *)contentRect
style:(int)aStyle
backing:(int)bufferingType
buttonMask:(int)mask
defer:(BOOL)flag

Creates, if necessary, and returns a new instance of SavePanel.  Each application shares just one instance of SavePanel; this method returns the shared instance if it exists.  A simpler interface is available via the inherited method new, which invokes this method with all the appropriate parameters.

See also:  + setSavePanelFactory:

NS_DEV_DOCFOR:objc_method:[SavePanel-setSavePanelFactory:];,setSavePanelFactory:

+ setSavePanelFactory:class

Sets the class from which SavePanel will be instantiated.  class should be a subclass of SavePanel.  If you want to use your own SavePanel subclass, your application must invoke this method before it creates the shared instance of SavePanel, or else free the shared instance before invoking this method.  When the newContent:style:backing: 	buttonMask:defer: method is invoked, the object it returns will belong to class.  

See also:  + newContent:style:backing:buttonMask:defer:

Instance Methods

NS_DEV_DOCFOR:objc_method:[SavePanel-accessoryView];,accessoryView

- accessoryView

Returns the view set by setAccessoryView:.

See also:  - setAccessoryView:

NS_DEV_DOCFOR:objc_method:[SavePanel-cancel:];,cancel:

- cancel:sender

This method is the action message sent by the Cancel button to the SavePanel.  Returns self.

NS_DEV_DOCFOR:objc_method:[SavePanel-commandKey:];,commandKey:

- (BOOL)commandKey:(NXEvent *)theEvent

This method is used to accept command-key events.  If theEvent contains a Command-Space, the SavePanel will do file name completion; if it contains a Command-H, the SavePanel jumps to the user's home directory.  Other command-key events are ignored.  Returns YES.

NS_DEV_DOCFOR:objc_method:[SavePanel-directory];,directory

- (const char *)directory

Returns the path of the directory that the SavePanel is currently showing.

NS_DEV_DOCFOR:objc_method:[SavePanel-doesTreatFilePackagesAsDirectories];,doesTreatFilePackagesAsDirectories

- (BOOL)doesTreatFilePackagesAsDirectories

Tests whether the SavePanel displays file packages to the user as directories.  Returns YES (the default)  if the user is shown files and subdirectories within a file package.  Returns NO if the user is shown only file package names, with no indication that they are directories.  

See also:  - setTreatsFilePackagesAsDirectories:

NS_DEV_DOCFOR:objc_method:[SavePanel-filename];,filename

- (const char *)filename

Returns the filenameÐincluding the path to the fileÐthat the SavePanel last accepted. 

NS_DEV_DOCFOR:objc_method:[SavePanel-free];,free

- free

Frees all storage used by the SavePanel.

NS_DEV_DOCFOR:objc_method:[SavePanel-ok:];,ok:

- ok:sender

This method is the action message sent by the OK button to the SavePanel.

NS_DEV_DOCFOR:objc_method:[SavePanel-requiredFileType];,requiredFileType

- (const char *)requiredFileType

Returns the last type set by setRequiredFileType:.

NS_DEV_DOCFOR:objc_method:[SavePanel-runModal];,runModal

- (int)runModal

Displays the panel and begins its event loop.  Invokes Application's runModalFor: method with self as the argument.  Returns NX_OKTAG (if the user clicks the OK button) or NX_CANCELTAG (if the user clicks the Cancel button).  

See also:   - runModalFor: (Application)

NS_DEV_DOCFOR:objc_method:[SavePanel-runModalForDirectory:file:];,runModalForDirectory:file:

- (int)runModalForDirectory:(const char *)path file:(const char *)filename

Initializes the panel to the file specified by path and name, then displays it and begins its modal event loop.  Invokes Application's runModalFor: method with self as the argument.   Returns NX_OKTAG (if the user clicks the OK button) or NX_CANCELTAG (if the user clicks the Cancel button).  

See also:   - runModalFor: (Application)

NS_DEV_DOCFOR:objc_method:[SavePanel-selectText:];,selectText:

- selectText:sender

Advances the current browser selection one line when Tab is pressed (goes back one line when Shift-Tab is pressed).

NS_DEV_DOCFOR:objc_method:[SavePanel-setAccessoryView:];,setAccessoryView:

- setAccessoryView:aView

aView should be the top View in a view hierarchy which will be added just above the OK and Cancel buttons at the bottom of the panel.  The panel is automatically resized to accommodate aView.  This method can be called repeatedly to change the accessory view depending on the situation.  If aView is nil, any accessory view in the panel will be removed.

NS_DEV_DOCFOR:objc_method:[SavePanel-setDelegate:];,setDelegate:

- setDelegate:anObject

Makes anObject the SavePanel's delegate.  Returns self.

NS_DEV_DOCFOR:objc_method:[SavePanel-setDirectory:];,setDirectory:

- setDirectory:(const char *)path

Sets the current path in the SavePanel browser.  Returns self.

NS_DEV_DOCFOR:objc_method:[SavePanel-setPrompt:];,setPrompt:

- setPrompt:(const char *)prompt

Sets the title for the form field in which users type their entries into the panel.  This title will appear on all SavePanels (or all OpenPanels if the receiver of this message is an OpenPanel) in your application.  ªFile:º is the default prompt string.  Returns self.

NS_DEV_DOCFOR:objc_method:[SavePanel-setRequiredFileType:];,setRequiredFileType:

- setRequiredFileType:(const char *)type

Specifies the type, a file name extension to be appended to any selected files that don't already have that extension; for example, ªnibº.  type should not include the period that begins the extension.  Be careful to invoke this method each time the SavePanel is used for another file type within the application.  Returns self.

NS_DEV_DOCFOR:objc_method:[SavePanel-setTreatsFilePackagesAsDirectories:];,setTreatsFilePackagesAsDirectories:

-setTreatsFilePackagesAsDirectories:(BOOL)flag

Sets the SavePanel's behavior for displaying file packages to the user.  If flag is YES, the user is shown files and subdirectories within a file package.  If NO, the user is shown only file package names, with no indication that they are directories.  

See also:  - doesTreatFilePackagesAsDirectories

NS_DEV_DOCFOR:objc_method:[SavePanel-setTitle:];,setTitle:

- setTitle:(const char *)newTitle

Sets the title of the SavePanel to newTitle and returns self.  By default, ªSaveº is the title string.  If a SavePanel is adapted to other uses, its title should reflect the user action that brings it to the screen.

NS_DEV_DOCFOR:objc_method:[SavePanel-textDidEnd:endChar:];,textDidEnd:endChar:

- textDidEnd:textObject endChar:(unsigned short)endChar

Determines whether the key that ended text was Tab or Shift-Tab so that selectText: knows whether to move forward or backwards.  Returns self.

NS_DEV_DOCFOR:objc_method:[SavePanel-textDidGetKeys:isEmpty:];,textDidGetKeys:isEmpty:

- textDidGetKeys:textObject isEmpty:(BOOL)flag

Invoked by the Panel's text to indicate whether there is any text in the Panel.  Disables the OK button if there is no text in the Panel.

Methods Implemented by the Delegate 

NS_DEV_DOCFOR:objc_method:[SavePanel-panel:compareFilenames::checkCase:];,panel:compareFilenames::checkCase:

- (int)panel:sender 
compareFilenames:(const char *)fileName1 :(const char *)fileName2
checkCase:(BOOL)flag

Controls the ordering of files presented by the SavePanel.  This method should return 1 if fileName1 should precede fileName2, 0 if the two names are equivalent, and -1 if fileName2 should precede fileName1.  

Don't reorder file names in the SavePanel lightly, since it may confuse the user to have files in one SavePanel or OpenPanel ordered differently than those in other such panels or in the Workspace Manager.  SavePanel and OpenPanel's default behavior is to order files as they are in the Workspace Manager file viewer.  Note also that implementing this method will reduce the operating performance of the panel.

NS_DEV_DOCFOR:objc_method:[SavePanel-panel:filterFile:inDirectory:];,panel:filterFile:inDirectory:

- (BOOL)panel:sender 
filterFile:(const char *)filename
inDirectory:(const char *)directory

A SavePanell sends this message to the panel's delegate for each file or directory it is about to display in the browser.  The delegate can then determine whether the filename or directory should be displayed in the panel, giving it the ability to filter out items that it doesn't want the user to see or choose.  It returns YES if it is to be displayed, or NO if the SavePanel should ignore the file or directory.

NS_DEV_DOCFOR:objc_method:[SavePanel-panelValidateFilenames:];,panelValidateFilenames:

- (BOOL)panelValidateFilenames:sender

Sent to the panel's delegate.  The delegate can then determine whether the current file name in the SavePanel can be used; it returns YES if the file name is valid, or NO if the SavePanel should stay up and wait for the user to type in a different file name.  The delegate can get the file name in the SavePanel by sending a filename message back to sender.